CONFIGURATION¶

The preferred method of specifying configuration for a changer is as a "changer" section in amanda.conf(5). The tapedev parameter then indicates, by name, the changer that will be used by default by most Amanda programs. For example:

define changer hp-robot {


    tapedev "chg-robot:/dev/sg1"


    property "tape-device" "0=tape:/dev/nst0"


    property append "tape-device" "1=tape:/dev/nst1"


    device-property "BLOCK_SIZE" "512k"
}
# ...
tapedev "hp-robot"

Several changer drivers accept changer properties which control the behavior of the changer. These properties must be specified in a changer definition, as in the hp-robot example, above.

Devices, too, can take properties to control their behavior (see amanda-devices(7)). Device properties can come from four places: implicit device properties (from tapetype parameters), global device properties (from global device-property parameters), properties in device definitions, and properties in changer definitions. Properties are applied in this order, with later properties taking priority.

There are only three implicit properties: MAX_VOLUME_USAGE is set based on the tapetype length parameter, READ_BLOCK_SIZE is set if readblocksize is set, and BLOCK_SIZE is set based on the blocksize parameter.

Global device properties always apply. If the changer specifies a device by alias, then device properties from the definition apply. If the changer is specified by an alias, then properties from that definition applied.

chg-aggregate:changer (new)¶

define changer robot0 {


  tpchanger "chg-robot:/dev/sg0"


  property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
}
define changer robot1 {


  tpchanger "chg-robot:/dev/sg1"


  property "tape-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
}
define changer single {


  tpchanger "chg-single:/dev/rmt/4"
}
define changer aggregate {


  tpchanger "chg-aggregate:{robot0,robot1,single}"


  property "state-filename" "/etc/amanda/CONF/aggregate.state"
}
tpchanger "aggregate"

This changer driver allow to use two or more changers or standalone drive in sequence.

Properties¶

LOCK-TIMEOUT

STATE_FILENAME

chg-disk:VTAPEROOT (new)¶

tpchanger "chg-disk:/var/mnt/vtapes"
property "num-slot" "10"
property "auto-create-slot" "yes"
property "removable" "yes"
property "mount" "yes"
property "umount" "yes"
property "umount-lockfile" "/etc/amanda/conf/vtapes-lock"
property "umount-idle" "1"

This changer driver replaces the old chg-disk, supporting parallel access to vtapes stored in directories named slotN in the directory specified after chg-disk:. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots. This changer is fast-search capable.

The current slot can be accessed using the device name file:VTAPEROOT. This is useful for the amrestore(8) command line.

Properties¶

AUTO-CREATE-SLOT

LOCK-TIMEOUT

MOUNT

NUM-SLOT

REMOVABLE

UMOUNT

UMOUNT-LOCKFILE

UMOUNT-IDLE

chg-disk (old)¶

tapedev "file:/u01/vtapes"
tpchanger "chg-disk"
changerfile "chg-disk.conf"     # optional file

This changer script supports sequential access to vtapes stored in directories named slotN in the directory specified by the tapedev parameter. The configuration file parameter is:

LASTSLOT=number    # The number of slots, default to tapecycle setting.

This changer is not fast-search capable.

chg-multi:DEVICE-LIST¶

tpchanger "chg-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
changerfile "chg-multi-state"

This script simply round-robins a number of distinct device names, as specified in the tpchanger setting. It is useful when all volumes for a configuration have different device names -- for example, if you have many standalone drive. The changerfile must exist; it is used to save the state file.

The child devices are specified using the same syntax as for the RAIT device (see amanda-changers(7)). The range specification can be especially useful here:

tpchanger "chg-multi:s3:mycompany-backups/tape-{001..100}"

This changer is not fast-search capable.

Properties¶

FIRST-SLOT

LOCK-TIMEOUT

Special Operations¶

A number of special operations are available for chg-multi via amtape(8) subcommands.

The reset subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer.

The eject subcommand will eject the volume in the given drive

The clean subcommand is not yet implemented.

The update subcommand instructs the changer to update its state database. Given no arguments, the changer will scan all available slots, loading each tape and reading its label. Especially for large libraries, this can take a long time. If only a few slots have changed, they can be listed on the command line:

amtape CONFIG update 1-3,9

amtape CONFIG update 2=DailySet-028

amtape CONFIG update 1-3,9=

chg-multi (old)¶

tpchanger "chg-multi"
changerfile "chg-multi-state"

This script simply round-robins a number of distinct device names, as specified in its configuration file. It is useful when all volumes for a configuration have different device names -- for example, with S3 devices. The changerfile need not exist; it is used as a prefix for filenames of state files.

The configuration file has simple lines with a parameter and its value separated by a space. The # character introduces a comment. The configuration parameters are:

multieject

needeject

gravity

slot X

This changer is not fast-search capable.

chg-manual¶

tpchanger "chg-manual"
changerfile "chg-manual.conf"

This script simply provides distinct device names in a round-robin fashion, as specified in its configuration file. It is useful when all volumes for a configuration have different device names -- for example, with S3 devices. The configuration file parameters are (as listed in the script):

resend_mail=900       # resend mail every __ seconds
timeout_mail=604800   # time out after this many seconds (default 7 days)
request="[type]"      # How to request a new tape (default "tty_email")


  request="tty"       # Use the tty to ask the user to change tape.


                      # Can't be use by cron


  request="email"     # Send an email to ask the user to change tape.


  request="tty_email" # Use the tty if it exist or send an email.

This changer is not fast-search capable.

chg-zd-mtx (old)¶

tpchanger "chg-zd-mtx"
changerdev "/dev/sg0"         # used with 'mtx -f'
changerfile "chg-zd-mtx.conf"
tapedev "tape:/dev/nst0"

This script interfaces with a tape drive using the Zubkoff/Dandelion version of mtx. That's the version that takes a device specifier with the -f option and has subcommands like status. The configuration file parameters are (as listed in the script itself):

firstslot=?                 #### First storage slot (element)
lastslot=?                  #### Last storage slot (element)
cleanslot=-1                #### Slot with cleaner tape -- default is "-1"


                            #### Set negative to indicate no cleaner available
driveslot=0                 #### Drive slot number.  Defaults to 0


                            #### Use the 'Data Transfer Element' you want
autoclean=0                 #### Set to '1' or greater to enable
autocleancount=99           #### Number of access before a clean.
havereader=0                #### If you have a barcode reader, set to 1.
offline_before_unload=0     #### Does your robot require an


                            #### 'mt offline' before mtx unload?
poll_drive_ready=NN         #### Time (seconds) between tests to see if


                            #### the tape drive has gone ready (default: 3).
max_drive_wait=NN           #### Maximum time (seconds) to wait for the


                            #### tape drive to become ready (default: 120).
initial_poll_delay=NN       #### initial delay after load before polling for


                            #### readiness
slotinfofile=FILENAME       #### record slot information to this file, in


                            #### the line-based format "SLOT LABEL\n"

This changer is fast-search capable if and only if havereader is true.

chg-rait:{CHILD1,CHILD2,..}¶

define changer vtape {


    tpchanger "chg-disk:/path/to/vtape"
}
define changer robot {


    tpchanger "chg-robot:/dev/sg0"


    tapedev "tape:/dev/nst0"
}
tpchanger "chg-rait:{vtape,robot}"

This changer script constructs RAIT devices out of the devices provided by several "sub-changers". The sub-changers are specified using the same shell-like syntax as the RAIT device (see amanda-devices(7)).

Chg-rait does not require that all of the child changers have the same slot names: compound slot names are created by combining the slot names supplied by the child changers using the same shell-like syntax. For example, if the child changers return slots "top", "strange", and "3", then the RAIT changer will return "{top,strange,3}". This makes it possible to, for example, mirror data on tapes in slots 1-10 to tapes in slots 11-20 of the same robot, using two chg-zd-mtx child changers (and, naturally, two tape drives). In this arrangement, the first slot would be named {1,11}.

As a convenience to the user, the RAIT changer will also accept un-braced slot names, and supply the same name to each child changer. Thus with a 4-device RAIT changer, "17" is equivalent to "{17,17,17,17}".

Drive names are parsed in a similar fashion, for operations that take drive names (clean and eject).

This changer is fast-search capable only if all of its child changers are fast-search capable.

chg-null:¶

tpchanger "chg-null:"

This changer always provides the device "null:". It is sometimes useful in conjunction with chg-rait:.

chg-robot:DEVICE¶

define changer robot {


    tpchanger "chg-robot:/dev/sg0"


    property "tape-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"


    property "eject-before-unload" "yes"


    property "use-slots" "1-5,11-20"
}
tpchanger "robot"

This changer drives a robotic tape library using the operating system's mtx command. It replaces the ancient chg-zd-mtx script. The changer uses all of the information available to operate as efficiently as possible. Even without a barcode reader, the changer can usually load a tape immediately, without resorting to a sequential scan of many tapes. It is capable of sharing state across multiple Amanda configurations, avoiding conflicts and optimally tracking the contents of the library.

This changer does not accept a changerdev parameter, but the changerfile parameter can be used to specify a filename at which it should store its state. Ordinarily, this state is stored in a file named after the changer device under $localstatedir/amanda, e.g., /var/amanda/chg-robot-dev-sg0. There should be a single such statefile for each distinct tape library attached to the Amanda server, even if multiple Amanda configurations reference that library.

With a barcode reader present, it is possible for chg-robot to track the state of the library reliably, even recognizing tapes that are removed and later re-inserted (by remembering their barcodes). Without barcodes, the changer can still remember the slot in which it last saw the tape with a particular label, although this information can become stale if the tapes are rearranged by an operator. In any case, the changer will never "hunt" for a tape by repeatedly loading slots and checking labels. If the changer's state is inaccurate, use the amtape(8) subcommand update.

This changer is fast-search capable even without a barcode reader. For such libraries, it is the responsibility of the operator to update the changer when tapes are added to or removed from the library.

There is a shell script in the contrib/ directory of Amanda's source distribution which can help you convert a chg-zd-mtx configuration into a chg-robot configuration. Just give it your Amanda configuration name:

  sh contrib/convert-zd-mtx-to-robot.sh $config

Special Operations¶

A number of special operations are available for chg-robot via amtape(8) subcommands.

The reset subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer.

The eject subcommand will unload the volume in the given drive, ejecting first if the changer properties dictate. Note that, despite the subcommand name, the changer attempts to avoid the state where a volume has been ejected from the drive but not unloaded back to a storage slot.

The clean subcommand is not yet implemented.

The update subcommand instructs the changer to update its state database. Given no arguments, the changer will scan all available slots, loading each tape and reading its label. Especially for large libraries, this can take a long time. If only a few slots have changed, they can be listed on the command line:

amtape CONFIG update 1-3,9

amtape CONFIG update 2=DailySet-028

amtape CONFIG update 1-3,9=

Properties¶

DRIVE-CHOICE

EJECT-BEFORE-UNLOAD

EJECT-DELAY

FAST-SEARCH

IGNORE-BARCODES

LOAD-POLL

"D [poll P [until U]]"

property "load-poll" "13s"

property "load-poll" "13s poll 5s"

property "load-poll" "0s poll 5s until 2m"

LOCK-TIMEOUT

MTX

STATUS-INTERVAL

TAPE-DEVICE

UNLOAD-DELAY

USE-SLOTS

Timing¶

Tape libraries are fickle, and in many cases will report that an operation is complete when it is still in progress. Chg-robot takes several timing-related properties to accomodate such behavior.

A typical sequence of operations performed during a load are: get library status, eject a tape, unload the tape back to a storage slot, load a new tape, and read the label on that tape to ensure the drive is ready.

On most systems, the library status check is nearly instantaneous -- the changer library provides its cached state to the host without initiating any robot motion. In order to keep its metadata up-to-date, chg-robot runs this command very frequently, but this frequency can be reduced (at the cost of potentially stale metadata) by setting the STATUS-INTERVAL property to a larger value.

Some tape libraries do not integrate the eject operation (performed by the embedded tape drive) with the unload operation (performed by the library robot), and can actually cause physical damage by attempting to remove the tape before the ejection is complete. For such changers, set the EJECT-DELAY property to allow enough time for the eject to complete.

Once a tape is unloaded, if the library needs time to "quiesce" before processing another command, add that time to the UNLOAD-DELAY parameter. No other operations will be performed on the library until this delay has elapsed.

Once a tape has been loaded, chg-robot waits until the drive is ready before allowing Amanda to use the volume, as described for LOAD-POLL, above.

Each of the times specified in these properties may be given as integers with the optional suffix s for seconds (the default) or m for minutes.

chg-ndmp:HOST[:PORT]@SCSIDEV¶

    tpchanger "chg-ndmp:filer.company.com@/dev/sg0"


    property        "tape-device" "0=ndmp:filer.company.com@/dev/rtape0"


    property append "tape-device" "1=ndmp:filer.company.com@/dev/rtape1"


    property "use-slots" "1-12"


    property "ndmp-auth" "text"


    property "ndmp-username" "luke"


    property "ndmp-password" "leia"

This changer is very similar to chg-robot, but controls a tape changer on an NDMP server instead of a local device. The HOST in the tpchanger should be the hostname of the NDMP server. The PORT is optional. The SCSIDEV should specify the SCSI device on the NDMP server which controls the changer. The format of this parameter is implementation-specific.

The appropriate authentication properties will be automatically set on any devices created by this changer.

Properties¶

This changer supports all of the properties supported by chg-robot, although the value of MTX is ignored. The following properties are also recognized:

NDMP_AUTH

NDMP-PASSWORD

NDMP-USERNAME

VERBOSE

chg-single:DEVICE¶

tpchanger "chg-single:tape:/dev/nst0"

This changer is for use with standalone drive, it can work with any device. The device (tape:/dev/nst0) must be set in the tpchanger definition.

The chg-single changer has no property.

Unmaintained Changers¶

Amanda has many other changer scripts and programs beyond those described here (see the changer-src/ in the source directory), but most of these scripts are unmaintained and undocumented, and will be removed when the new changer API is fully implemented.